Python 包分发：PyPI 发布与版本管理

Python 庞大的生态系统由海量的软件包驱动，这些包都可以通过 Python 包索引 (PyPI) 轻松获取。本指南全面概述了如何通过 PyPI 分发您自己的 Python 包，确保全球的开发者都能访问它们。我们将探讨必要的工具、版本管理的最佳实践，以及创建和发布高质量 Python 包的工作流程。

为什么要分发您的 Python 包？

分发您的 Python 包能带来诸多好处：

• 分享您的工作： 允许其他开发者轻松复用您的代码，促进协作和创新。想象一下，一个全球团队正在使用您用 Python 构建的专业数据分析工具。
• 依赖管理： 简化了其他项目中管理依赖项的过程。您的包及其所有依赖项只需一条命令即可安装。
• 开源贡献： 使您能够为开源社区做出贡献，并为您的工作赢得认可。许多关键的软件组件都是由全球开发者维护的开源包。
• 版本控制和更新： 提供了一种结构化的方式来管理版本、发布更新和修复错误。这确保了用户始终能访问到最新、最可靠的包版本。
• 安装简便： 通过 `pip install your-package-name` 为用户简化了安装过程。

Python 包分发的核心工具

有几种工具对于创建和分发 Python 包至关重要：

• setuptools: 一个广泛使用的库，用于定义包的元数据，包括名称、版本、依赖项和入口点。它是打包 Python 项目的事实标准。
• wheel: 一种分发格式，与源码分发相比，它提供了更高效、更可靠的安装过程。Wheel 是预构建的分发包，无需编译即可安装。
• twine: 一个用于安全地将您的包上传到 PyPI 的工具。Twine 在传输过程中会加密您的凭据和包数据，防止窃听和中间人攻击。
• venv/virtualenv: 这些是用于创建隔离的 Python 环境的工具。使用虚拟环境对于管理依赖项和避免不同项目之间的冲突至关重要。

设置您的项目

在分发您的包之前，您需要正确地构建项目结构。

项目结构示例

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

说明：

• my_package/: 包含您包源代码的主目录。
• my_package/__init__.py: 使 `my_package` 目录成为一个 Python 包。它可以是空的，也可以包含初始化代码。
• my_package/module1.py, my_package/module2.py: 包含实际代码的 Python 模块。
• tests/: 包含单元测试的目录。编写测试对于确保包的质量和可靠性至关重要。
• README.md: 一个 Markdown 文件，提供您的包的描述、使用说明和其他相关信息。这通常是用户在 PyPI 上首先看到的内容。
• LICENSE: 一个包含您的包分发所依据的许可证的文件（例如，MIT、Apache 2.0、GPL）。选择适当的许可证对于明确他人如何使用您的代码至关重要。
• setup.py: 定义包元数据和构建指令的主要配置文件。
• .gitignore: 指定应被 Git 忽略的文件和目录（例如，临时文件、构建产物）。

创建 `setup.py` 文件

`setup.py` 文件是您包分发的核心。它包含了关于您的包的元数据以及构建和安装它的指令。以下是一个示例：

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # 替换为您的包名
    version="0.1.0",
    author="您的名字",  # 替换为您的名字
    author_email="your.email@example.com", # 替换为您的电子邮件
    description="一个小示例包",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # 替换为您的仓库 URL
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # 依赖示例
    ],
)

说明：

• name: 您的包名，将用于 PyPI。请选择一个独特且具描述性的名称。
• version: 您的包的版本号。请遵循语义化版本（见下文）。
• author, author_email: 您的姓名和电子邮件地址。
• description: 您的包的简短描述。
• long_description: 更长、更详细的描述，通常从您的 `README.md` 文件中读取。
• long_description_content_type: 指定长描述的格式（例如，"text/markdown"）。
• url: 您的包主页的 URL（例如，GitHub 仓库）。
• packages: 要包含在分发包中的包列表。`setuptools.find_packages()` 会自动发现您项目中的所有包。
• classifiers: 帮助用户在 PyPI 上找到您的包的元数据。请从 Trove 分类器列表 中选择合适的分类器。考虑包含支持的 Python 版本、操作系统和许可证的分类器。
• python_requires: 指定使用您的包所需的最低 Python 版本。
• install_requires: 您的包所需的依赖项列表。这些依赖项将在安装您的包时自动安装。

版本管理：语义化版本

语义化版本（SemVer）是一种被广泛采用的版本方案，它提供了一种清晰一致的方式来传达包中变更的性质。

一个 SemVer 版本号由三部分组成：MAJOR.MINOR.PATCH（主版本号.次版本号.修订号）。

• MAJOR（主版本号）： 当您进行不兼容的 API 更改时递增。这表示一个重大变化，可能需要用户更新他们的代码。
• MINOR（次版本号）： 当您以向后兼容的方式添加功能时递增。这表示新增了功能或改进，但不会破坏现有代码。
• PATCH（修订号）： 当您进行向后兼容的错误修复时递增。这用于小的修复，不添加新功能或破坏现有功能。

示例：

• 1.0.0: 初始版本。
• 1.1.0: 新增了功能，但未破坏现有代码。
• 1.0.1: 修复了 1.0.0 版本中的一个错误。
• 2.0.0: 进行了不兼容的 API 更改。

使用 SemVer 有助于用户理解升级到新版本包所带来的影响。

构建您的包

一旦配置好 `setup.py` 文件，您就可以构建您的包了。

1. 创建虚拟环境： 强烈建议创建一个虚拟环境来隔离您包的依赖项。使用 `python3 -m venv .venv`（或 `virtualenv .venv`），然后激活它（在 Linux/macOS 上是 `source .venv/bin/activate`，在 Windows 上是 `.venv\Scripts\activate`）。
2. 安装构建依赖： 运行 `pip install --upgrade setuptools wheel`。
3. 构建包： 运行 `python setup.py sdist bdist_wheel`。此命令会在 `dist` 目录中创建两个分发文件：一个源码分发包 (sdist) 和一个 wheel 分发包 (bdist_wheel)。

`sdist` 包含您的源代码和 `setup.py` 文件。`bdist_wheel` 是一个预构建的分发包，可以更快地安装。

将您的包发布到 PyPI

在发布您的包之前，您需要在 PyPI (https://pypi.org/) 上创建一个账户并创建一个 API 令牌。此令牌将用于验证您的上传操作。

1. 在 PyPI 上注册： 前往 https://pypi.org/account/register/ 并创建一个账户。
2. 创建 API 令牌： 前往 https://pypi.org/manage/account/，向下滚动到“API tokens”部分，然后创建一个新令牌。请安全地存储此令牌，因为上传包时需要用到它。
3. 安装 Twine： 运行 `pip install twine`。
4. 上传您的包： 运行 `twine upload dist/*`。系统会提示您输入用户名（应为 `__token__`）和密码（您创建的 API 令牌）。

重要安全提示： 切勿将您的 API 令牌提交到您的代码仓库。请安全地存储它，并在上传过程中使用环境变量或其他安全方法来访问它。

测试您的包安装

发布您的包之后，测试它是否能正确安装是至关重要的一步。

1. 创建一个新的虚拟环境： 这可以确保您在一个干净的环境中测试安装。
2. 安装您的包： 运行 `pip install your-package-name`。
3. 导入并使用您的包： 在 Python 解释器中，导入您的包并验证其是否按预期工作。

持续集成和持续部署 (CI/CD)

为了自动化构建、测试和发布包的过程，您可以使用 CI/CD 工具，如 GitHub Actions、GitLab CI 或 Travis CI。

以下是一个 GitHub Actions 工作流程示例，它可以构建您的包并将其发布到 PyPI：

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

说明：

• 此工作流程在 GitHub 上发布新版本 (release) 时触发。
• 它会检出代码、设置 Python、安装依赖项、构建包，然后将其上传到 PyPI。
• secrets.PYPI_API_TOKEN 是一个 GitHub secret，用于存储您的 PyPI API 令牌。您需要在 GitHub 仓库的设置中配置此 secret。

Python 包分发的最佳实践

• 编写全面的文档： 包括详细的 `README.md` 文件以及使用 Sphinx 等工具生成的 API 文档。清晰完整的文档对于使您的包易于使用至关重要。
• 编写单元测试： 全面测试您的代码以确保其质量和可靠性。使用像 pytest 或 unittest 这样的测试框架。
• 遵循 PEP 8 风格指南： 遵守 Python 增强提案 8 (PEP 8) 风格指南，以确保代码的一致性和可读性。
• 使用许可证： 选择一个合适的开源许可证，以明确他人如何使用您的代码。
• 保持依赖项更新： 定期更新您包的依赖项，以受益于错误修复、安全补丁和新功能。
• 使用虚拟环境： 始终在虚拟环境中开发和测试您的包，以隔离依赖项。
• 考虑国际化 (i18n) 和本地化 (l10n)： 如果您的包处理面向用户的文本或数据，请考虑使其能适应不同的语言和地区。这可以扩大您的全球潜在用户群。像 Babel 这样的工具可以帮助实现这一点。
• 处理不同的时区和货币： 如果您的包处理日期、时间或金融交易，请注意世界各地的不同时区和货币。使用适当的库和 API 来正确处理这些复杂性。
• 提供清晰的错误信息： 编写信息丰富的错误消息，帮助用户理解问题所在以及如何修复。如果可能，将这些错误消息翻译成不同的语言。
• 考虑可访问性： 在设计包的界面和文档时，请考虑残障用户。遵循可访问性指南，确保您的包对每个人都可用。

高级主题

• 命名空间包： 允许您将单个 Python 包拆分到多个目录甚至多个分发包中。
• 入口点： 允许您定义可以从其他包或命令行调用的函数或类。
• 数据文件： 允许您在分发包中包含非 Python 文件（例如，数据文件、配置文件）。
• 条件依赖： 允许您指定仅在特定条件下（例如，在特定的操作系统上）才需要的依赖项。

结论

在 PyPI 上分发您的 Python 包是与世界分享您的工作并为 Python 生态系统做出贡献的绝佳方式。通过遵循本指南中概述的步骤和最佳实践，您可以创建和发布易于安装、使用和维护的高质量 Python 包。请记住，优先考虑清晰的文档、全面的测试和一致的版本管理，以确保您的包取得成功。